/*
 * Copyright (c) 2007, 2015, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */
/*
 * Copyright 2001, 2002,2004 The Apache Software Foundation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.sun.org.apache.xerces.internal.xni.parser;

import java.io.IOException;
import java.util.Locale;

import com.sun.org.apache.xerces.internal.xni.XMLDocumentHandler;
import com.sun.org.apache.xerces.internal.xni.XMLDTDHandler;
import com.sun.org.apache.xerces.internal.xni.XMLDTDContentModelHandler;
import com.sun.org.apache.xerces.internal.xni.XNIException;

/**
 * Represents a parser configuration. The parser configuration maintains
 * a table of recognized features and properties, assembles components
 * for the parsing pipeline, and is responsible for initiating parsing
 * of an XML document.
 * <p>
 * By separating the configuration of a parser from the specific parser
 * instance, applications can create new configurations and re-use the
 * existing parser components and external API generators (e.g. the
 * DOMParser and SAXParser).
 * <p>
 * The internals of any specific parser configuration instance are hidden.
 * Therefore, each configuration may implement the parsing mechanism any
 * way necessary. However, the parser configuration should follow these
 * guidelines:
 * <ul>
 * <li>
 * Call the <code>reset</code> method on each component before parsing.
 * This is only required if the configuration is re-using existing
 * components that conform to the <code>XMLComponent</code> interface.
 * If the configuration uses all custom parts, then it is free to
 * implement everything as it sees fit as long as it follows the
 * other guidelines.
 * </li>
 * <li>
 * Call the <code>setFeature</code> and <code>setProperty</code> method
 * on each component during parsing to propagate features and properties
 * that have changed. This is only required if the configuration is
 * re-using existing components that conform to the <code>XMLComponent</code>
 * interface. If the configuration uses all custom parts, then it is free
 * to implement everything as it sees fit as long as it follows the other
 * guidelines.
 * </li>
 * <li>
 * Pass the same unique String references for all symbols that are
 * propagated to the registered handlers. Symbols include, but may not
 * be limited to, the names of elements and attributes (including their
 * uri, prefix, and localpart). This is suggested but not an absolute
 * must. However, the standard parser components may require access to
 * the same symbol table for creation of unique symbol references to be
 * propagated in the XNI pipeline.
 * </li>
 * </ul>
 *
 * @author Arnaud  Le Hors, IBM
 * @author Andy Clark, IBM
 */
public interface XMLParserConfiguration
    extends XMLComponentManager {

  //
  // XMLParserConfiguration methods
  //

  // parsing

  /**
   * Parse an XML document.
   * <p>
   * The parser can use this method to instruct this configuration
   * to begin parsing an XML document from any valid input source
   * (a character stream, a byte stream, or a URI).
   * <p>
   * Parsers may not invoke this method while a parse is in progress.
   * Once a parse is complete, the parser may then parse another XML
   * document.
   * <p>
   * This method is synchronous: it will not return until parsing
   * has ended.  If a client application wants to terminate
   * parsing early, it should throw an exception.
   * <p>
   * When this method returns, all characters streams and byte streams
   * opened by the parser are closed.
   *
   * @param inputSource The input source for the top-level of the XML document.
   * @throws XNIException Any XNI exception, possibly wrapping another exception.
   * @throws IOException An IO exception from the parser, possibly from a byte stream or character
   * stream supplied by the parser.
   */
  public void parse(XMLInputSource inputSource)
      throws XNIException, IOException;

  // generic configuration

  /**
   * Allows a parser to add parser specific features to be recognized
   * and managed by the parser configuration.
   *
   * @param featureIds An array of the additional feature identifiers to be recognized.
   */
  public void addRecognizedFeatures(String[] featureIds);

  /**
   * Sets the state of a feature. This method is called by the parser
   * and gets propagated to components in this parser configuration.
   *
   * @param featureId The feature identifier.
   * @param state The state of the feature.
   * @throws XMLConfigurationException Thrown if there is a configuration error.
   */
  public void setFeature(String featureId, boolean state)
      throws XMLConfigurationException;

  /**
   * Returns the state of a feature.
   *
   * @param featureId The feature identifier.
   * @throws XMLConfigurationException Thrown if there is a configuration error.
   */
  public boolean getFeature(String featureId)
      throws XMLConfigurationException;

  /**
   * Allows a parser to add parser specific properties to be recognized
   * and managed by the parser configuration.
   *
   * @param propertyIds An array of the additional property identifiers to be recognized.
   */
  public void addRecognizedProperties(String[] propertyIds);

  /**
   * Sets the value of a property. This method is called by the parser
   * and gets propagated to components in this parser configuration.
   *
   * @param propertyId The property identifier.
   * @param value The value of the property.
   * @throws XMLConfigurationException Thrown if there is a configuration error.
   */
  public void setProperty(String propertyId, Object value)
      throws XMLConfigurationException;

  /**
   * Returns the value of a property.
   *
   * @param propertyId The property identifier.
   * @throws XMLConfigurationException Thrown if there is a configuration error.
   */
  public Object getProperty(String propertyId)
      throws XMLConfigurationException;

  // handlers

  /**
   * Sets the error handler.
   *
   * @param errorHandler The error resolver.
   */
  public void setErrorHandler(XMLErrorHandler errorHandler);

  /**
   * Returns the registered error handler.
   */
  public XMLErrorHandler getErrorHandler();

  /**
   * Sets the document handler to receive information about the document.
   *
   * @param documentHandler The document handler.
   */
  public void setDocumentHandler(XMLDocumentHandler documentHandler);

  /**
   * Returns the registered document handler.
   */
  public XMLDocumentHandler getDocumentHandler();

  /**
   * Sets the DTD handler.
   *
   * @param dtdHandler The DTD handler.
   */
  public void setDTDHandler(XMLDTDHandler dtdHandler);

  /**
   * Returns the registered DTD handler.
   */
  public XMLDTDHandler getDTDHandler();

  /**
   * Sets the DTD content model handler.
   *
   * @param dtdContentModelHandler The DTD content model handler.
   */
  public void setDTDContentModelHandler(XMLDTDContentModelHandler dtdContentModelHandler);

  /**
   * Returns the registered DTD content model handler.
   */
  public XMLDTDContentModelHandler getDTDContentModelHandler();

  // other settings

  /**
   * Sets the entity resolver.
   *
   * @param entityResolver The new entity resolver.
   */
  public void setEntityResolver(XMLEntityResolver entityResolver);

  /**
   * Returns the registered entity resolver.
   */
  public XMLEntityResolver getEntityResolver();

  /**
   * Set the locale to use for messages.
   *
   * @param locale The locale object to use for localization of messages.
   * @throws XNIException Thrown if the parser does not support the specified locale.
   */
  public void setLocale(Locale locale) throws XNIException;

  /**
   * Returns the locale.
   */
  public Locale getLocale();

} // interface XMLParserConfiguration
